mcp-azeth

Deploy a new Azeth smart account with guardian guardrails and register it on the ERC-8004 trust registry.

Use this when: An AI agent or service needs its own on-chain identity with spending limits and trust registry presence. One EOA can own multiple smart accounts.

Single atomic transaction: deploys smart account proxy, installs all 4 modules (Guardian, TrustRegistry, PaymentAgreement, Reputation), registers on ERC-8004, and permanently revokes factory access.

Returns: The deployed smart account address, trust registry token ID, and transaction hash.

Gas is automatically sponsored — no ETH required. The SDK uses a gasless relay (EIP-712 signature) so the account can be created without any pre-funding. On testnet, USDC is also auto-funded.

Guardian: By default, the guardian is derived from AZETH_GUARDIAN_KEY env var. If not set, falls back to self-guardian (owner address). For production, always use a separate guardian key. Set AZETH_GUARDIAN_KEY in your .env file.

Example: { "name": "PriceFeedBot", "entityType": "service", "description": "Real-time crypto price data", "capabilities": ["price-feed", "market-data"] }

Check all balances with USD values for your EOA and all Azeth smart accounts.

Use this when: You need to know how much ETH, USDC, or WETH your accounts hold, or you want a total portfolio value in USD before making a transfer or payment.

Returns: Multi-account breakdown with per-token USD values and grand total. EOA is shown first (index 0), followed by smart accounts in deployment order.

Optionally filter to a single smart account by providing its address.

Note: This is a read-only, single-RPC-call operation and safe to call repeatedly. The owner is determined by the AZETH_PRIVATE_KEY environment variable.

Example: {} or { "smartAccount": "#1" }

Get recent transaction history for your Azeth smart account.

Use this when: You need to review past transactions, verify a payment was sent, or audit account activity.

Returns: Array of transaction records with hash, from, to, value, block number, and timestamp.

Note: Full indexed history requires the Azeth server to be running. Returns empty results if the server is unavailable. The account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "limit": 5 } or { "smartAccount": "#2", "limit": 20 }

Deposit ETH or ERC-20 tokens from your EOA wallet into your own Azeth smart account.

Use this when: Your smart account needs funding for transfers, x402 payments, or other operations.

SECURITY: This verifies ON-CHAIN that the target is a real Azeth smart account owned by you. You cannot deposit to someone else's smart account.

Returns: Transaction hash and deposit details.

Note: If no target account is specified, deposits to your first smart account. For ETH deposits, omit the token parameter. For ERC-20 tokens, provide the token contract address AND decimals. The amount is in human-readable units (e.g., "0.01" for 0.01 ETH, "100" for 100 USDC).

Example: { "amount": "0.01" } or { "amount": "50", "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "decimals": 6 }

List all your Azeth smart accounts with their names, addresses, and trust registry token IDs.

Use this when: You want to see all your accounts at a glance, find an account by name, or get the "#N" index for use in other tools.

Returns: Your EOA owner address and an indexed list of smart accounts. Each account shows its #N index (usable in other tools), name, address, and tokenId.

Note: This is a read-only operation. Names come from the trust registry. The owner is determined by the AZETH_PRIVATE_KEY environment variable.

Add or remove a token from your smart account's guardian whitelist.

Use this when: You need to whitelist a new token for payment agreements or other executor-module operations. Newly created accounts already have ETH, USDC, and WETH whitelisted by default.

Why it matters: The GuardianModule enforces a token whitelist for automated operations (payment agreements, swap execution). Owner-signed transfers bypass the whitelist, but executor modules like PaymentAgreementModule require the token to be whitelisted.

Returns: Transaction hash confirming the whitelist update.

Note: Only the account owner can update their own whitelist.

Example: { "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "allowed": true }

Send ETH or ERC-20 tokens FROM your Azeth smart account to another address.

Use this when: You need to pay another participant, fund an account, or move tokens between addresses.

The "to" field accepts: an Ethereum address, a participant name (resolved via trust registry), "me" (your first smart account), or "#N" (Nth account index from azeth_accounts).

IMPORTANT: This sends FROM your smart account, not your EOA. Ensure your smart account is funded. Use azeth_deposit first to fund your smart account if needed. One EOA can own multiple smart accounts — specify which one, or defaults to first.

Returns: Transaction hash, sender smart account address, recipient address (with resolution info), and amount sent.

Note: This is a state-changing operation. The tool shows the resolved address before executing. For ETH transfers, omit the token parameter. For ERC-20 tokens, provide the token contract address AND decimals. The amount is in human-readable units (e.g., "1.5" for 1.5 ETH or "100" for 100 USDC). The sender account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "to": "Alice", "amount": "0.001" } or { "to": "0x1234...abcd", "amount": "10", "token": "0x036C...CF7e", "decimals": 6 }

Pay for an x402-gated HTTP service. Makes the request, handles 402 payment automatically, and returns the response.

Use this when: You need to access a paid API or service that uses the x402 payment protocol (HTTP 402). The tool automatically detects if you have an active payment agreement (subscription) with the service. If an agreement exists, access is granted without additional payment. Otherwise, a fresh USDC payment is signed.

Returns: Whether payment was made, the payment method used (x402/session/none), the HTTP status, and the response body.

Note: Requires USDC balance to pay (unless an agreement grants access). Set maxAmount to cap spending. Only HTTPS URLs to public endpoints are accepted. The payer account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "url": "https://api.example.com/data" } or { "url": "https://api.example.com/data", "maxAmount": "1.00" }

Discover the best service for a capability and pay for it automatically.

Use this when: You need a service by CAPABILITY (e.g., "price-feed", "market-data", "translation") and want Azeth to pick the highest-reputation provider, handle payment, and fall back to alternatives if needed.

How it differs from azeth_pay:

• azeth_smart_pay: "I need price-feed data" → Azeth discovers the best service, pays it, returns the data.

• azeth_pay: "I need data from https://specific-service.com/api" → You know which service, Azeth pays it.

Flow: Discovers services ranked by reputation → tries the best one → if it fails, tries the next. Set autoFeedback: true to automatically submit a reputation opinion based on service quality after payment. Note: autoFeedback defaults to false in MCP context (ephemeral client). Enable it if the MCP server has a bundler configured.

Returns: The response data, which service was used, how many attempts were needed, and payment details.

Example: { "capability": "price-feed" } or { "capability": "translation", "maxAmount": "0.50", "method": "POST", "body": "{"text": "hello"}" }

Set up a recurring payment agreement to another participant. Payments execute on a fixed interval.

Use this when: You need automated recurring payments (subscriptions, data feeds, scheduled transfers) between participants.

Returns: The agreement ID and creation transaction hash.

Note: This creates an on-chain agreement via the PaymentAgreementModule. The payee or anyone can call execute once each interval has elapsed. Requires sufficient token balance for each execution. The payer account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "payee": "Alice", "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "amount": "1.00", "intervalSeconds": 86400 }

Subscribe to an x402-gated service by creating a payment agreement.

Use this when: You want to set up a subscription instead of paying per-request. The tool fetches the service URL, parses the 402 payment-agreement extension terms, and creates an on-chain payment agreement matching those terms.

Returns: The agreement ID, transaction hash, and subscription details.

Note: The service must advertise payment-agreement terms in its 402 response. After subscribing, subsequent calls to azeth_pay will automatically detect the agreement. No need to pass an agreementId — the server recognizes your wallet via SIWx authentication.

Execute a due payment from an on-chain agreement. Anyone can call this — the payer, payee, or a third-party keeper.

Use this when: You are a service provider collecting a recurring payment owed to you, a payer triggering your own agreement manually, or a keeper bot executing due agreements.

Keeper support: When the "account" is a foreign address (not owned by your private key), execution routes through your own account or EOA automatically. No special configuration needed.

The contract validates all conditions on-chain: interval elapsed, active, within caps and limits. Pro-rata accrual means the payout scales with elapsed time (capped at 3x the interval).

Returns: Transaction hash, amount paid, execution count, and next execution time. If the agreement soft-fails (insufficient balance, guardian limit), it returns the failure reason without reverting.

Cancel an active payment agreement. Only the payer (agreement creator) can cancel.

Use this when: You want to stop a recurring payment subscription or data feed. Cancellation is immediate — no timelock, no penalty. Already-paid amounts are not refunded.

Returns: Transaction hash and final agreement state (total paid, execution count).

View full details of a payment agreement including status, payment history, and next execution time.

Use this when: You want to inspect an agreement before executing or cancelling it, verify terms after creation, or check how much has been paid so far.

Returns: Complete agreement details with human-readable amounts, status, and timing.

Note: This is a read-only on-chain query. No gas or private key required for the query itself, but account resolution may need your key if using "me" or "#N".

List all payment agreements for a smart account with summary status.

Use this when: You need to find an agreement ID, see all active subscriptions, check which agreements are due for execution, or get an overview of payment commitments.

Returns: Array of agreement summaries sorted by ID (newest first), with status and timing.

Note: This is a read-only on-chain query. Iterates through all agreements for the account. For accounts with many agreements, this may take a few seconds.

Find all payment agreements that are due for execution across one or more accounts.

Use this when: You are a keeper bot looking for agreements to execute, or a service provider checking which of your customers' payments are collectible.

Returns: Array of due agreements with payer account, agreement ID, and expected payout. Each entry can be passed directly to azeth_execute_agreement.

Note: This scans all agreements for the specified accounts. For large-scale keeper operations, consider filtering by specific accounts rather than scanning all.

Register a service, agent, or infrastructure on the ERC-8004 trust registry with metadata and capabilities.

Use this when: You want to make your agent or service discoverable by other participants in the Azeth network.

Returns: The trust registry token ID and creation transaction hash.

Note: This is a state-changing on-chain operation. The token ID is your permanent identity in the trust registry. Other participants can discover you by capability, entity type, and reputation score. The account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "name": "MarketOracle", "description": "Real-time market data API", "entityType": "service", "capabilities": ["price-feed", "market-data"], "endpoint": "https://api.example.com" }

Find services, agents, and infrastructure on the trust registry by capability, entity type, and reputation.

Use this when: You need to find a participant that offers a specific capability (e.g., "swap", "price-feed"), or you want to browse available services filtered by type and minimum reputation score.

Returns: Array of registry entries with token ID, owner, entity type, name, capabilities, endpoint, and status.

Note: This queries the Azeth server API. Set AZETH_SERVER_URL env var if the server is not at the default location. Results are ranked by reputation score. No private key is required for read-only discovery.

Example: { "capability": "price-feed" } or { "entityType": "service", "minReputation": 50, "limit": 5 }

Look up a specific participant on the trust registry by token ID or smart account address.

Use this when: You know a specific agent/service address or token ID and want to see their registration details, capabilities, and reputation.

Provide EITHER tokenId OR address (at least one required). If address is provided, it is resolved to a token ID via on-chain lookup.

Returns: Full registry entry including name, description, entity type, capabilities, endpoint, and weighted reputation score.

This is read-only and safe to call at any time.

Example: { "address": "0x1234..." } or { "tokenId": "5" }

Update metadata for your registered service on the trust registry.

Use this when: You need to change your service endpoint, description, capabilities, or other metadata after initial registration with azeth_publish_service.

Supported metadata keys: "endpoint", "description", "capabilities", "name", "entityType", "pricing". For capabilities, provide a JSON array string (e.g., '["translation", "nlp"]').

Note: Catalogs are off-chain and served from your endpoint. Update your catalog by updating the response at your endpoint, not via this tool.

Returns: Confirmation with transaction hash.

Note: Your account must already be registered on the trust registry. This requires a transaction (gas cost). Only the account owner can update metadata.

Example: { "key": "endpoint", "value": "https://api.example.com/v2" }

Update multiple metadata fields for your registered service in a single transaction.

Use this when: You need to change several metadata fields at once (e.g., endpoint + description + capabilities). This is more gas-efficient than calling azeth_update_service multiple times.

Supported metadata keys: "endpoint", "description", "capabilities", "name", "entityType", "pricing". For capabilities, provide a JSON array string (e.g., '["translation", "nlp"]').

Note: Catalogs are off-chain. Update your catalog by updating your endpoint response.

Returns: Confirmation with a single transaction hash for all updates.

Note: All updates are atomic — if one fails, none are applied. Maximum 5 key-value pairs per batch.

Example: { "updates": [{"key": "endpoint", "value": "https://api.example.com/v2"}, {"key": "description", "value": "Updated service"}] }

Submit payment-gated reputation opinion for an agent or service on the ERC-8004 Reputation Registry.

Use this when: You have interacted with an agent/service and want to rate their performance. Opinion weight is determined by how much you have paid the target in USD (payment-gated). If you update your opinion for the same agent, the previous entry is automatically revoked.

Returns: The transaction hash of the opinion submission.

Note: This is a state-changing on-chain operation via the Azeth ReputationModule. The rating field is a number from -100 to 100 (supports decimals like 85.5). Stored on-chain in WAD format (18-decimal) for consistent aggregation. You must have a minimum USD payment to the target (payment-gated). Tags allow categorization (e.g., tag1="quality", tag2="x402"). The submitter account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "agentId": "1024", "rating": 85, "tag1": "quality", "tag2": "x402" } Example (negative): { "agentId": "1024", "rating": -50, "tag1": "reliability", "tag2": "downtime" }

Get USD-weighted reputation for an agent from the on-chain ReputationModule.

Use this when: You want to check the reputation of an agent or service before interacting. Returns a weighted average where each rater's influence is proportional to their USD payment to the agent.

Returns: Weighted reputation with weightedValue (int256), totalWeight, and opinionCount.

Note: This is a read-only on-chain query. No private key or gas is required. Leave raters empty to aggregate across all raters who have submitted opinions.

Example: { "agentId": "1024" } or { "agentId": "1024", "raters": ["0x1234...abcd"] }

Check how much one account has paid another — either total USD or per-token.

Use this when: You want to verify payment history between two accounts, which determines feedback weight in the payment-gated reputation system.

Two modes: • No token (default): Returns total net paid in 18-decimal USD, aggregated across all tokens via the on-chain oracle. Always >= 0. • With token: Returns the signed per-token delta. Positive = "from" paid more, negative = "to" paid more. Use 0x0...0 for native ETH.

"from" defaults to your own address ("me") if omitted. "to" accepts a name, address, or "me".

Note: This is a read-only on-chain query. No private key or gas is required (unless "me" or a name is used for resolution).

Example: { "to": "Alice" } or { "from": "#1", "to": "Bob", "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e" }

Check if you have an active reputation opinion for a specific agent.

Use this when: You want to verify whether you have already submitted a reputation opinion for an agent before submitting a new one (which would overwrite the existing one).

The agentId is the ERC-8004 token ID of the agent you want to check. Use azeth_discover_services or azeth_get_registry_entry to find token IDs.

Returns: Whether an active opinion exists and its opinion index on the reputation registry.

This is read-only and safe to call at any time.

Example: { "agentId": "3" }

Send an encrypted message to another participant via the XMTP messaging network.

Use this when: You need to communicate with another agent or service using end-to-end encrypted messaging. The recipient must be reachable on the XMTP network (use azeth_check_reachability first if unsure).

The "to" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).

Returns: The conversation ID and recipient address confirming delivery.

Note: This is NOT idempotent — each call sends a new message. The sender account is determined by the AZETH_PRIVATE_KEY environment variable. Messages are limited to 10,000 characters.

Example: { "to": "Alice", "content": "Hello, I would like to use your price-feed service." }

Check if an Ethereum address is reachable on the XMTP messaging network.

Use this when: You want to verify a participant can receive XMTP messages before sending. This is a read-like operation and safe to retry.

The "address" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).

Returns: The address and whether it is reachable (boolean).

Note: Reachability is cached for 5 minutes. An address is reachable if it has an active XMTP identity. The checking account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "address": "Alice" } or { "address": "0x1234567890abcdef1234567890abcdef12345678" }

Read incoming encrypted messages from the XMTP messaging network.

Use this when: You want to check for messages from other agents or services. This is the "inbox" view — it lets you read what others have sent you.

Two modes:

1. With "from": Read messages from a specific sender (up to "limit" messages)

2. Without "from": Read the latest message from each conversation (inbox overview)

The "from" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).

Returns: Array of messages with sender address, content, timestamp, and conversation ID.

Note: XMTP messages are end-to-end encrypted. The account reading messages is determined by the AZETH_PRIVATE_KEY environment variable. First call may be slow due to XMTP initialization.

Example: { "from": "Alice", "limit": 10 } or { } (all conversations)

List all active XMTP messaging conversations.

Use this when: You want to see who you have been communicating with, or check if a conversation exists with a specific peer.

Returns: Array of conversations with peer address and creation time.

Note: First call may be slow due to XMTP initialization.

Example: { }

Discover what services an agent offers by sending them a capabilities request over XMTP.

Use this when: You want to find out what services another agent provides, their pricing, and how to use them — before making a service request or payment.

Sends a JSON capabilities request to the target agent and waits for their response. The target agent must be online and have a MessageRouter configured to respond.

The "agentAddress" field accepts: an Ethereum address, a participant name, "me", or "#N" (account index).

Returns: The agent's capabilities including services, pricing, and usage instructions. If no response within the timeout, returns an error indicating the agent may be offline.

Example: { "agentAddress": "0x1234567890abcdef1234567890abcdef12345678" }

View the guardian security configuration for a smart account.

Use this when: You want to check spending limits, token/protocol whitelists, daily spend tracking, emergency withdrawal status, or pending guardrail changes.

Returns: Full guardian state including spending limits (USD), whitelisted tokens and protocols, daily spend progress, and any pending timelock changes.

This is read-only and safe to call at any time.

Example: { "smartAccount": "me" }

Add or remove a protocol (contract address) from your smart account's guardian whitelist.

Use this when: You need to interact with a new DeFi protocol or contract through executor modules (like PaymentAgreementModule). Protocols must be whitelisted for automated operations to succeed.

The "protocol" field must be a valid Ethereum address of the contract to whitelist.

Returns: Confirmation of the whitelist update with transaction hash.

Note: This requires a UserOperation (gas). Only the account owner can modify whitelists. Whitelisting a protocol allows executor modules to interact with it on your behalf. Whitelist additions require guardian co-signature for security.

Example: { "protocol": "0x71D52798e3D0f5766f6f0AFEd6710EB5D1FF4DF9", "allowed": true }

Review and approve or reject guardian approval requests from agents you protect.

Azeth smart accounts have a guardian who co-signs high-value operations. When an agent exceeds its autonomous spending limits, it sends you (the guardian) an approval request via XMTP. Use this tool to review and respond to those requests.

Three modes:

1. No request_id: Lists all pending guardian approval requests from your XMTP inbox

2. request_id + decision "approve": Co-signs the userOpHash and sends approval via XMTP

3. request_id + decision "reject": Sends rejection with optional reason via XMTP

When approving, this tool signs the userOpHash with your AZETH_PRIVATE_KEY (which is the guardian key on your MCP instance) and sends the signature back to the requesting agent.

Returns: List of pending requests (mode 1), or confirmation of approve/reject (mode 2/3).

Example (list): { } Example (approve): { "request_id": "abc-123", "decision": "approve" } Example (reject): { "request_id": "abc-123", "decision": "reject", "reason": "Amount too high" }

Check the status of a pending guardian approval request.

Use this when: You previously submitted an operation that required guardian co-signature and received a timeout with a request_id. This tool checks if the guardian has since responded via XMTP.

Status outcomes:

• "approved": Guardian approved. Returns the guardian signature. Retry your original operation — it will now succeed with the guardian co-signature.

• "rejected": Guardian rejected with a reason.

• "pending": Guardian has not responded yet. Check again later.

• "expired": Request expired after 5 minutes. Retry your original operation.

Returns: Current status and relevant details (signature if approved, reason if rejected).

Example: { "request_id": "abc-123" }